{
 "metadata": {
  "name": "",
  "signature": "sha256:4cbf97157ef27b2d1adb1a1d5468c4117930a856485e7e0fc94538459c372846"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Taking Measurements"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In Ubuntu, the OpenDrop.py file can be made \"double-clickable\" by changing the default Nautilus preferences (Edit --> Preferences --> Behaviour). \n",
      "\n",
      "Alternatively, run the code in the terminal using the script file \"run\" with the command:\n",
      "```tcsh\n",
      ".\\run\n",
      "```\n",
      "The following window will open, ready for user input:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/menu.png\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Here we can set the physical properties of the system, and choose the graphical outputs we want to show as opendrop is running. (Note that the needle diameter can be either selected from the dropdown box, or entered manually). We also choose the directory and the file we want our output data to be written to. We can also specify whether we want to use an already generated image (\"Local images\"), or whether we want to acquire and process images using a camera (currently either Flea3 or USB). If we choose a camera source, we can also set the number of images we want to process and the wait time in seconds between each image. \n",
      "\n",
      "For the purposes of this tutorial, enter an output filename prefix, select \"Local images\", and then press \"Run\". The following window will open, asking you to select the image for processing."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/file_select.png\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Navigate to \"test_images\", and select \"water_in_air.png\". The following window should open, prompting you to select the region of the image that contains the drop:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/drop_selection.png\" height=\"630\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Select the region defining the drop by clicking and holding the left mouse button and dragging a box around the drop. Whilst the mouse button is being pressed the box will be red:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/drop_selectionA.png\" height=\"630\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Once you release the mouse button the box will be green:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/drop_selectionB.png\" height=\"630\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you are happy that the drop region has been defined sufficiently, press \"enter\" or \"space\". Otherwise repeat the procedure outlined above to define another box. Make sure that you don't include any of the needle within the box, and that enough of the drop is selected such that the algorithm can converge to an accurate solution. \n",
      "\n",
      "Once you have defined the drop region, another window will open asking you to draw a box around a portion of the needle. This procedure is the same as for the drop region. Make sure you select a region that is clear from any visible contamination or aberrations. Once you are happy, press \"enter\" or \"space\"."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/needle_selectionB.png\" height=\"630\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Opendrop will now start the fitting routine. The following two windows will open, plotting the fitted Young-Laplace solution on the drop image, and also the residuals of the fit as the routine progresses."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/drop_profile.png\" height=\"611\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<img src=\"files/images/residuals.png\" height=\"611\" width=\"720\">"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Also, opendrop will write some data to the terminal, showing the iteration number, an error estimate, and its current guesses for the fitting parameters."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "```tcsh\n",
      "Processing frame 1 of 1...\n",
      "__________________________________________________________________________\n",
      "| Step |  Error   | x-centre | z-centre | Apex R_0 |   Bond   | w degree |\n",
      "|   1  |   0.7254 | 510.0042 | 355.0740 | 190.4734 |  0.21730 | -0.74084 |\n",
      "|   2  |   0.2172 | 510.0236 | 355.0909 | 190.4750 |  0.21725 | -0.74488 |\n",
      "|   3  |   0.2171 | 510.0237 | 355.0909 | 190.4750 |  0.21725 | -0.74489 |\n",
      "|   4  |   0.2171 | 510.0237 | 355.0909 | 190.4750 |  0.21725 | -0.74489 |\n",
      "Convergence in parameters\n",
      "\n",
      "```"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Finally, a .csv file will be written to the directory specified at the start, with your specified name and a date-time stamp, containing the final solution:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "```bash\n",
      "Time (s),IFT (mN/m),Volume (uL),Area (mm2),x-apex (px),y-apex (px),Apex radius (px),Bond number,Rotation (degree)\n",
      "   0.00000,  71.78098,  10.95089,  23.80818, 510.02365, 355.09087, 190.47503,   0.21725,  -0.01300\n",
      "```"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For image sequences, this data can also be plotted in real-time by selecting \"Physical quantities\" from the start menu."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you use this software in your research, please cite the following journal article:\n",
      "\n",
      "J. D. Berry, M. J. Neeson, R. R. Dagastine, D. Y. C. Chan and R. F. Tabor, Measurement of surface and interfacial tension using pendant drop tensiometry. Journal of Colloid and Interface Science (2015)\n",
      "\n",
      "Here it is in BibTex form:\n",
      "```\n",
      "@Article{OpenDrop:2015,\n",
      "  Author    = {Berry, J.D. and Neeson, M.J. and Dagastine, R.R. and Chan, D.Y.C. and Tabor, R.F.},\n",
      "  Title     = {Measurement of surface and interfacial tension using pendant drop tensiometry},\n",
      "  Journal   = {Journal of Colloid and Interface Science},\n",
      "  Volume    = {},\n",
      "  Number    = {},\n",
      "  Pages     = {},\n",
      "  month     = may,\n",
      "  year      = 2015,\n",
      "  doi       = {10.1016/j.jcis.2015.05.012},\n",
      "}\n",
      "```\n",
      "\n",
      "These citations help us not only to understand who is using and developing OpenDrop, and for what purpose, but also to justify continued development of this code and other open source resources."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [],
     "language": "python",
     "metadata": {},
     "outputs": []
    }
   ],
   "metadata": {}
  }
 ]
}
